This tutorial was created to give a basic introduction to creating plugins for the User Blog Mod.
For this tutorial I will be referring to the Custom Title plugin.


1. Package Layout
[quote]The file layout for the plugin package should be the same as other mods for phpBB.  It is your choice if you want to use the ModX standard or the plain text standard.  For this tutorial I will be referring to the plain text standard, because the Custom Title plugin does not require any extra file edits to the core of phpBB3.[/quote]

plugin_name (main folder)
[list]
[*]contrib/
For extra files, like for example the hook list if your mod has hooks others can use in the plugin system or the plain text install file if you are using the ModX format (if you want to include one).
[*]root/
Contains all of the files the user needs to upload.
[*]premod_root/
If the modifications done to phpBB3 are extensive enough that you would like to include premodified files,
put those in this folder.[/list]
2. File layout
[quote]Here is the list of locations you should use for putting your plugin files.[/quote]
[list]
[*]blog/plugins/info/
In here you have the basic plugin information (will get to more of this later)
[*]blog/plugins/plugin_name/
Here you should put all of the files you need to include to run this plugin.

The following files are REQUIRED to be included with the mod in this folder:
[list]
[*]index.htm (so users can not browse the folder in a web browser)
[*]install.php (contains the database install information, if your mod does not require db modifications then keep the file blank)
[*]uninstall.php (same as the install.php file, but for uninstalling the database sections)
[*]update.php (same as install.php, except for updating between versions)[/list]
[*]language/(lang)/mods/blog/plugins/
In here you should have a language file for the plugin.[/list]
3. File use/information (referring to the Custom Title plugin)
[quote]This will give some more detailed information on how to use the files and setup a basic plugin.[/quote]
blog/plugins/info/info_custom_title.php
[quote]This file must start with info_ or it will be ignored by the plugins system.[/quote]

Page Setup:
[list]
[*][code]$user->add_lang('mods/blog/plugins/' . $name);

$this->available_plugins[$name]['plugin_title'] = $user->lang['BLOG_CUSTOM_TITLE_TITLE'];
$this->available_plugins[$name]['plugin_description'] = $user->lang['BLOG_CUSTOM_TITLE_DESCRIPTION'];[/code]
[quote]First, add the language options, then set the title and description of the plugin (this is displayed in the ACP).[/quote]

[*][quote]Then you should set the copyright information and version number for the plugin.[/quote]
[code]$this->available_plugins[$name]['plugin_copyright'] = '2008 EXreaction';
$this->available_plugins[$name]['plugin_version'] = '1.0.0';[/code]

[*][code]	$to_do = array(
		'user_handle_data'			=> array('custom_title_user_handle_data'),
	);[/code]
[quote]Here you setup the hooks list and the name of the correlating function you would like to be called.

In this example, it is set so that when the user_handle_data hook is called, the custom_title_user_handle_data function (which we have in blog/plugins/custom_title/functions.php) is called.

The list of hooks is available in the contrib/ folder for the User Blog Mod package.  You should look and see exactly what variables are being passed and how they are being passed for each hook you use.

If you ever build something that requires a new hook to be added, do not hesitate to contact me about it.  If I feel that putting a hook in the location you request is needed, I will add the hook.  However, you should do whatever possible to use the existing hooks.[/quote]

[*][code]foreach($to_do as $do => $what)
{
	if (!array_key_exists($do, self::$to_do))
	{
		self::$to_do[$do] = $what;
	}
	else
	{
		self::$to_do[$do] = array_merge(self::$to_do[$do], $what);
	}
}[/code]
[quote]This code is required to add the hooks to the to_do list for the plugins class.  If your plugin uses any hooks you must use that code to add the hooks.[/quote]

[*][code]include($blog_plugins_path . 'custom_title/functions.' . $phpEx);[/code]
[quote]Here you should include any extra files you need, in this case, the custom_title/functions file holds the custom_title_user_handle_data function which will be called by user_handle_data.[/quote]

[*][quote]If you are outputting information to the template and compiling a template to do so, you [b]must[/b] use the blog_plugins::parse_template() function to do so![/quote]

Instead of the normal method of:
[code]		$template->set_filenames(array(
			'custom_title_body'		=> 'blog/plugins/custom_title/custom_title.html',
		));

		$args['menu'] .= $template->assign_display('custom_title_body');[/code]

Use something like this:
[code]$args['menu'] .= blog_plugins::parse_template('blog/plugins/custom_title/custom_title.html');[/code]

Not only does this make things shorter and simpler to develop, but that function verifies that the template file you are using exists in the style the user is viewing and uses the one from prosilver in the event that the file is missing from where it should be.
[b]Note that this only works in the User Blog Mod RC2 or newer.[/b][/list]

I hope this helps you start to create your own plugins for the User Blog modification, if you have any further questions do not hesitate to ask.

Happy codding!